<!--
  ~ Copyright (c) 2005 - 2014, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License"); you may not
  ~ use this file except in compliance with the License. You may obtain a copy
  ~ of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software distributed
  ~ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
  ~ CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations under the License.
  -->

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head><title>Event Receiver - User Guide</title>

    <link href="../../admin/css/documentation.css" rel="stylesheet" type="text/css" media="all"/>
</head>
<body>
<h1>Event Receiver</h1>

<h2>Configuring WSO2Event Event Receiver</h2>

<p>This will convert the events which coming from Siddhi in to wso2Events according to the mapping
   configurations.</p>

<p>Hence WSO2Event has three data types (Meta, Correlation and Payload), the CEP back end runtime
   event attributes can be mapped to any one of them by adding the mapping configuration under their
   type names.</p>

<h3>Configuring through the Management Console UI</h3>

<p>1. Log in to the CEP management console and select the <strong>Main</strong> menu in the left
   hand side of the screen. Then select the <strong>Add</strong> menu item under <strong>Event
                                                                                         Receiver</strong>
   menu.</p>

<p>2. The <strong>Create a New Event Receiver</strong> window opens, using which you can configure
   new event receivers. Enter the following details in the form to create a wso2Event mapping based
   event receiver as shown in the screenshot below.</p>

<p><br/><img src="../images/wso2EventReceiver.png" alt="Create Event Receiver"/></p>

<p>Here, there are several properties that need to be filled when creating a event receiver. User
   interface is divided in to 3 main components (From, Mapping and To) except the event receiver
   name to give more understanding to the user.</p>
<ul>
    <li>Event Receiver Name - Property that used to uniquely identify a event receiver
        configuration.
    </li>
    <li>Event Stream - Can select a event stream (Stream name with version) where you going to
        listen for events, It is numbered as "1".
    </li>
    <li>Stream Attributes - Based on the event stream selected, It shows what are the attributes
        available at that stream. (It is only for reference when creating output mapping)
    </li>
    <li>Output Event Adapter Name - Event adapter which you going to use to publish the events from
        CEP. (Output Event Adapters which are created are listed here). It is numbered as "2". Based
        on the Event Adapter that selected sections "3", "4" and "5" will change accordingly.
    </li>
    <li>Output Mapping Type - This property can be change based on the event adapter selected. Some
        event adapters can support for multiple types of mappings. User can select the required
        mapping type from the list. Is is numbered as "3".
    </li>
    <li>Stream Definition - Since, you have selected WSO2Event type event adapter "wso2EventSender";
        you need a stream to send events from CEP.
    </li>
    <li>Stream Version - Version of the event stream.</li>
</ul>
<h5>WSO2Event Mapping</h5>

<p>WSO2Event contains three types of data properties. They are Meta Data, Correlation Data and
   Payload Data. Each data property needs to have</p>
<ul>
    <li>Name - The attribute name to which the event data will be mapped when creating the output
        WSO2Event
    </li>
    <li>Value Of - The attribute/property name from which the data element to be mapped</li>
    <li>Type - Type of the element that is being mapped. This can be either of java.lang.String,
        java.lang.Integer, java.lang.Long, or java.lang.Double.
    </li>
</ul>
<div>3. After adding details click the <strong>Add Event Receiver</strong> button. The <strong>Available
                                                                                                Event
                                                                                                Receiver</strong>
     page will open. To view event receiver configurations, click on the event receiver name. To
     delete event receiver, click the <strong>Delete</strong> button.
</div>
<p><br/><img src="../images/wso2EventReceiverDetails.png" alt="Create Event Receiver"/></p>

<p>
    <br/>
    <span style="color: rgb(0,0,0);font-family: Arial , Verdana , Helvetica , sans-serif;font-size: 20.0px;font-weight: bold;line-height: normal;">Editing Event Receiver Configuration through the Management Console</span>
</p>

<p>By Clicking the <strong>Edit</strong> button of the relevant event receiver, you will able to
   edit the event receiver configuration and redeploy it. When you click the Edit button, it will
   redirect to a xml based editor window which allow you to edit the event receiver configuration
   from UI without opening the configuration file in the file system.</p>

<p><br/><img src="../images/editWSO2EventReceiver.png" alt="Create Event Receiver"/></p>

<h3>Configuring through a xml File</h3>

<p>You can specify a event receiver configuration through in a xml file and deploy it in the
   deployment directory in the server. Event Receiver deployment directory is available at &lt;CARBON_HOME&gt;/repository/deployment/server/eventreceivers
   . This is an hot deployment directory, then it is easy to deploy and undeploy an event receiver
   configuration.</p>

<p>1. Create a xml file and enter the following WSO2Event mapping event receiver configurations
   inside the above mentioned hot deployment directory. Event receiver implementation needs to be
   start with "eventreceiver" root element.</p>
<pre>&lt;eventReceiver name="StatisticsReceiver" xmlns="http://wso2.org/carbon/eventreceiver"&gt;
        &lt;from streamName="statisticsStream" version="1.0.0"/&gt;
        &lt;mapping type="wso2event"&gt;
            &lt;metaData&gt;
                &lt;property&gt;
                    &lt;from name="ipAddress"/&gt;
                    &lt;to name="ipAdd" type="string"/&gt;
                &lt;/property&gt;
            &lt;/metaData&gt;
            &lt;payloadData&gt;
                &lt;property&gt;
                    &lt;from name="user"/&gt;
                    &lt;to name="username" type="string"/&gt;
                &lt;/property&gt;
            &lt;/payloadData&gt;
        &lt;/mapping&gt;
        &lt;to eventAdapterType="wso2EventSender" eventAdapterType="wso2event"&gt;
            &lt;property name="stream"&gt;statisticsOutStream&lt;/property&gt;
            &lt;property name="version"&gt;1.0.0&lt;/property&gt;
            &lt;/to>
    &lt;/eventReceiver></pre>

<p>For more details on creating different types of event receivers, Please refer the official
   documentation <a
            href="http://docs.wso2.org/display/CEP300/Working+with+Event+Receivers">Here.</a>
</p>

</body>
</html>

